Scripting
Documentation
Changelog
Privacy
Documentation
Changelog
Privacy

Mail

The Mail module allows your script to present a native mail compose view, enabling users to send emails with recipients, subject, body, and attachments prefilled. It also provides a way to check whether the device is capable of sending emails.

Mail.isAvailable: boolean

Returns true if the device is configured to send emails using the built-in Mail app.

1if (!Mail.isAvailable) {
2  console.log("Mail is not available on this device.")
3}

Mail.present(options): Promise<"cancelled" | "sent" | "failed" | "saved">

Presents the system mail composer with the provided options. Users can edit the message, then send, cancel, or save it as a draft.

Parameters

Name Type Required Description
toRecipients string[] Yes List of email addresses to include in the To field.
ccRecipients string[] No List of email addresses for the CC (carbon copy) field.
bccRecipients string[] No List of email addresses for the BCC (blind carbon copy) field.
preferredSendingEmailAddress string No If the user has multiple accounts configured, this can specify the preferred sender's email.
subject string No Email subject line.
body string No The content of the email body.
attachments Attachment[] No Array of files to attach to the email.

Attachment Object

Each attachment must include the following fields:

Property Type Required Description
data Data Yes The binary content to attach.
mimeType string Yes The MIME type (e.g., "image/png", "application/pdf").
fileName string Yes Name of the file as it will appear in the email.

Return Value

Returns a Promise that resolves to one of the following result strings:

  • "sent" – The user sent the email.
  • "cancelled" – The user cancelled email composition.
  • "failed" – Sending failed due to an error (e.g., no email account configured).
  • "saved" – The email was saved as a draft.

Throws

This method will throw an error if:

  • Mail.isAvailable is false
  • The options are malformed or missing required fields

Example: Simple Email

1if (Mail.isAvailable) {
2  const result = await Mail.present({
3    toRecipients: ["user@example.com"],
4    subject: "Hello from script",
5    body: "This email was sent using the Scripting app!"
6  })
7
8  console.log("Result:", result) // sent, cancelled, failed, or saved
9}

Example: Email with Attachment

1const fileData = Data.fromString("Here is the content of the attached file.")
2
3if (Mail.isAvailable) {
4  const result = await Mail.present({
5    toRecipients: ["user@example.com"],
6    subject: "Document attached",
7    body: "Please find the document attached.",
8    attachments: [
9      {
10        data: fileData,
11        mimeType: "text/plain",
12        fileName: "notes.txt"
13      }
14    ]
15  })
16
17  if (result === "sent") {
18    console.log("Email successfully sent.")
19  } else {
20    console.log("Email not sent:", result)
21  }
22}

Notes

  • The system mail composer must be presented in an interactive context (not in background-only scripts).
  • The user controls the final sending of the message.
  • This API requires a properly configured mail account.
Outline